How to localize ChangeDesktop

ChangeDesktop can be localized for any language supported by Mac OS X without having to change any of the code. All strings that are displayed to the user are stored in separate files that can be edited with any Unicode text editor.

Steps to localize ChangeDesktop (CD). If you have questions after reviewing this document, please send them to cdapp@classicalguitar.net. There is also an example of how to do a localization without Interface Builder at the end of this document.

1. Download and install Apple's developer tools. Localization can be done without the developer tools but it is easier if you have the Dev Tools installed.

2. Copy the CD bundle to you hard disk.

3. Ctrl-click on the CD bundle you just copied and choose "Show Package Contents" from the menu.

4. In the resulting window, open the Contents and then Resources folders.

5. In the Resources folder, duplicate the English.lproj folder and rename it for your localized language. The Mac OS X System Overview book contains more information <http://developer.apple.com/techpubs/macosx/Essentials/SystemOverview/SystemOverview.pdf>.

Examples.
Spanish = Spanish.lproj
Japanese = Japanese.lproj
Swedish = Swedish.lproj

6. In the Resources directory, you will also find bundles named ChangeDesktopDaemon and ChangeDesktopMenu. Repeat steps three through five for both of these bundles.

7. Each new language folder you created can contain two types of files. String files (.strings) and NIB files (.nib). Both of these file types need to be localized.

The ChangeDesktop documentation should be localized too. The documentation files are located in the Documentation/en folder. Duplicate the 'en' folder and rename it to the two letter code for your localization. The files consists of LaTeX source files and PDF screenshots.

7a. String files are unicode text files and are formated as follows.

"String Name" = "String Contents";

To edit these files you should open them in Project Builder (or any editor that understands Unicode, such as TextEdit or BBEdit). You must not change the string on the left of the equals character, only the string on the right of it. Also, the semi-colon at the end of the line must be present. Note: If you use TextEdit to edit these files, you must use the Unicode Plain Text Encoding when saving the file.

Example:

(DON'T EDIT)     (Localize this string)
InfoAskCheck = "Do you want to check the internet for a new version of ChangeDesktop?";

7b. NIB files are binary files and can either be edited directly with Apple's Interface Builder app., or exported to a Strings file and edited with a text editor. If you use Interface Builder, please make sure to translate the Tool Tip and secondary title strings. These can be found in the Inspector for each object.

If you are unfamiliar with Interface Builder, then follow these steps to export the NIB strings and then create a new NIB file. This requires the use of the command line tool 'nibtool' which is part of Apple's Dev Tools. If you can not (or do not want to) install the Dev Tools, e-mail me at cdapp@classicalguitar.net and I will send you the nibtool binary.

	1. Open Terminal.app.
	2. Type 'cd ' (without quotes) on the command line. Do not hit the return key yet.
	3. Drag and Drop the ChangeDesktop bundle from the Finder to the Terminal window. You should see the full path of the bundle appear in the window. Hit the return or enter key.
	4. Type cd 'Contents/Resources' (without quotes) and hit return.
	5. Type the following to export the NIB strings to a Strings file.

nibtool -L English.lproj/#FILE NAME#.nib >  #YOUR BUNDLE#.lproj/#FILE NAME#_NIB.strings

Replace #FILE NAME# with the name of the NIB file and replace #YOUR BUNDLE# with the name of the new localized bundle you have created.

	6. Open and edit the file created in step five as you would any other Strings file. Be very careful to only edit the String contents, especially when you get to the About Box text; it can be confusing. (Make sure to give yourself credit in the About Box text.)

	7. Once you have edited the NIB Strings file, you will need to create a new binary NIB file with your changes. To do this, type the following (assuming you are in the same directory as step five).

nibtool -d #YOUR BUNDLE#.lproj/#FILE NAME#_NIB.strings -W #YOUR BUNDLE#.lproj/#FILE NAME#.nib English.lproj/#FILE NAME#.nib

Replace #FILE NAME# with the name of the original NIB file and replace #YOUR BUNDLE# with the name of the new localized bundle you have created.

	8. Repeat steps 7b 1-7 for every NIB file. (Currently the only NIB files are found in the main CD bundle; ChangeDesktopDaemon and ChangeDesktopMenu do not contain any NIB files.)
	9. If you are familiar with Interface Builder you can now open the new localized NIB files and check to make sure all of the controls are sized properly to show the localized strings. I will do this if necessary, so you don't need to worry about it if you don't know how to use Interface Builder.

8. Try out your changes. Open the International Preferences Pane and make sure the language you have localized CD to is selected. Then launch CD and try things out.

9. Once you are satisfied, make a new Disk Image (or Stuffit or a tarball) archive with the whole CD bundle and send it to me at cdapp@classicalguitar.net.

Example Localization (w/o IB)

This example will localize ChangeDesktop to Spanish. This example is done completely with the command line. You can copy files from the Finder instead of using the command line. A dollar sign ($) at the beginning of a line in this sample represents the command line shell prompt and should not be reproduced when duplicating the sample. Comments on commands will be indented and start with a pound (#) character.

Please note that the new nib files (BBNetUpdate*) for the 2.1.2 release are not included in this example. They need to be translated for a "real" localization.

Assumptions:
	1. The Dev Tools (and therefore 'nibtool') are installed.
   	2. The ChangeDesktop install disk image is mounted at /Volumes/ChangeDesktop.
      	3. Line wraps in this example are ignored

	#Move to home directory
$cd

	#Copy the ChangeDesktop bundle
$cp -R /Volumes/ChangeDesktop/ChangeDesktop.app .

	#Move to the ChangeDesktop bundle resource folder
$cd ChangeDesktop.app/Contents/Resources

	#Duplicate all English.lproj folders
$cp -R ./English.lproj ./Spanish.lproj

$cd ChangeDesktopDaemon.app

$cp -R Contents/Resources/English.lproj Contents/Resources/Spanish.lproj

$cd ../ChangeDesktopMenu.menu

$cp -R Contents/Resources/English.lproj Contents/Resources/Spanish.lproj

	#Edit all String files. This is done by using the 'open' command, which will open the file with an editor in the GUI.
   	#If you are working in the Finder, just double-click on each String file.
   	#The first time you open a String file, you will have to choose an app to edit ".strings" files with.
$cd ..

$open Spanish.lproj/CDPStrings.strings

$open Spanish.lproj/FindPanel.strings

$cd ChangeDesktopDaemon.app

$open Contents/Resources/Spanish.lproj/Events.strings

$open Contents/Resources/Spanish.lproj/Errors.strings

$cd ../ChangeDesktopMenu.menu

$open Contents/Resources/Spanish.lproj/CDMenuStrings.string

	#Edit all NIB files
$cd ..

$nibtool -L English.lproj/ChangeDesktopPreferences.nib > Spanish.lproj/ChangeDesktopPreferences_NIB.strings

$open Spanish.lproj/ChangeDesktopPreferences_NIB.strings

	#After editing, create the new binary NIB file
$nibtool -d Spanish.lproj/ChangeDesktopPreferences_NIB.strings -W Spanish.lproj/ChangeDesktopPreferences.nib English.lproj/ChangeDesktopPreferences.nib

$nibtool -L English.lproj/FindPanel.nib > Spanish.lproj/FindPanel_NIB.strings

$open Spanish.lproj/FindPanel_NIB.strings

$nibtool -d Spanish.lproj/FindPanel_NIB.strings -W Spanish.lproj/FindPanel.nib English.lproj/FindPanel.nib